💰 API de Status Financeiro - Documentação Completa

📋 Visão Geral

A API de Status Financeiro é responsável por gerenciar o controle financeiro mensal dos usuários no sistema CordenaAi, incluindo consulta, criação e atualização do status de pagamento por usuário e mês. O sistema permite rastrear se um usuário está em dia ou em atraso com suas obrigações financeiras em um período específico.

🎯 Endpoints Disponíveis

1. GET /api/StatusFinanceiro

Listar Todos os Status Financeiros

2. GET /api/StatusFinanceiro/consultar

Consultar Status Financeiro

3. POST /api/StatusFinanceiro

Criar Status Financeiro

4. PUT /api/StatusFinanceiro

Atualizar Status Financeiro

🔧 Modelo de Dados

Estrutura do StatusFinanceiro

{
  "id": "int",
  "usuarioId": "string (GUID - 36 caracteres)",
  "mes": "string (formato: YYYY-MM)",
  "situacaoFinanceiro": "boolean (true = em dia, false = em atraso)",
  "dataCriacao": "datetime",
  "dataAtualizacao": "datetime"
}

DTOs de Request/Response

StatusFinanceiroDto (Response)

{
  "id": 1,
  "usuarioId": "c6b7e826-539b-4901-8453-fedf4e3d1896",
  "mes": "2025-01",
  "situacaoFinanceiro": true,
  "dataCriacao": "2025-01-15T10:30:00Z",
  "dataAtualizacao": "2025-01-15T10:30:00Z"
}

CriarStatusFinanceiroDto (Request)

{
  "usuarioId": "c6b7e826-539b-4901-8453-fedf4e3d1896",
  "mes": "2025-01"
}

AtualizarStatusFinanceiroDto (Request)

{
  "situacaoFinanceiro": true
}

🔐 Autenticação e Autorização

Todos os endpoints requerem:

📊 Casos de Uso Principais

1. Listagem de Todos os Status Financeiros

GET /api/StatusFinanceiro
Authorization: Bearer {token}

Resposta:

[
  {
    "id": 1,
    "usuarioId": "c6b7e826-539b-4901-8453-fedf4e3d1896",
    "mes": "2025-01",
    "situacaoFinanceiro": true,
    "dataCriacao": "2025-01-15T10:30:00Z",
    "dataAtualizacao": "2025-01-15T10:30:00Z"
  },
  {
    "id": 2,
    "usuarioId": "c6b7e826-539b-4901-8453-fedf4e3d1896",
    "mes": "2025-02",
    "situacaoFinanceiro": false,
    "dataCriacao": "2025-02-01T09:15:00Z",
    "dataAtualizacao": "2025-02-01T09:15:00Z"
  }
]

2. Consulta de Status Financeiro

GET /api/StatusFinanceiro/consultar?usuarioId=c6b7e826-539b-4901-8453-fedf4e3d1896&mes=2025-01
Authorization: Bearer {token}

Resposta (Status Existe):

{
  "id": 1,
  "usuarioId": "c6b7e826-539b-4901-8453-fedf4e3d1896",
  "mes": "2025-01",
  "situacaoFinanceiro": true,
  "dataCriacao": "2025-01-15T10:30:00Z",
  "dataAtualizacao": "2025-01-15T10:30:00Z"
}

Resposta (Status Não Existe):

{
  "usuarioId": "c6b7e826-539b-4901-8453-fedf4e3d1896",
  "mes": "2025-01",
  "situacaoFinanceiro": false,
  "dataCriacao": "2025-01-15T10:30:00Z",
  "dataAtualizacao": "2025-01-15T10:30:00Z"
}

3. Criação de Status Financeiro

POST /api/StatusFinanceiro
Content-Type: application/json
Authorization: Bearer {token}

{
  "usuarioId": "c6b7e826-539b-4901-8453-fedf4e3d1896",
  "mes": "2025-01"
}

4. Atualização de Status

PUT /api/StatusFinanceiro?usuarioId=c6b7e826-539b-4901-8453-fedf4e3d1896&mes=2025-01
Content-Type: application/json
Authorization: Bearer {token}

{
  "situacaoFinanceiro": true
}

⚠️ Validações e Regras de Negócio

Validações Obrigatórias

Regras de Negócio

Validações Específicas

🚨 Tratamento de Erros

Códigos de Status HTTP

Formato de Erro

{
  "error": "string",
  "message": "string",
  "details": "string",
  "timestamp": "datetime"
}

Exemplos de Erros

Formato de Mês Inválido:

{
  "error": "BadRequest",
  "message": "Formato de mês inválido: 2025/01. Use o formato YYYY-MM",
  "timestamp": "2025-01-15T10:30:00Z"
}

Registro Duplicado:

{
  "error": "Conflict",
  "message": "Já existe um registro para este usuário neste mês.",
  "timestamp": "2025-01-15T10:30:00Z"
}

📈 Performance e Limitações

Limitações

Otimizações

🔄 Integração com Outros Módulos

Módulos Relacionados

Fluxos de Integração

  1. Criação de Usuário → Criação automática de status financeiro
  2. Processamento de Pagamento → Atualização de status
  3. Relatórios Financeiros → Consulta de status por período
  4. Notificações → Alertas baseados em status

📱 Uso em Aplicações

Web App

Mobile App

Integrações Externas

🛠️ Manutenção e Monitoramento

Logs Importantes

Métricas Monitoradas

📚 Exemplos Práticos

Fluxo Completo de Gestão Financeira

  1. Consulta Inicial:

    GET /api/StatusFinanceiro/consultar?usuarioId={id}&mes=2025-01

  2. Criação de Status (se não existir):

    POST /api/StatusFinanceiro
{
  "usuarioId": "{id}",
  "mes": "2025-01"
}

  3. Atualização de Status (após pagamento):

    PUT /api/StatusFinanceiro?usuarioId={id}&mes=2025-01
{
  "situacaoFinanceiro": true
}

Fluxo de Relatório Financeiro

  1. Consulta por Período: Múltiplas consultas por usuário/mês
  2. Agregação de Dados: Consolidação de status por período
  3. Geração de Relatório: Análise de inadimplência
  4. Cache de Resultados: Otimização para próximas consultas

Casos de Uso Específicos

Gestão de Inadimplência

Controle de Pagamentos

Versão: 1.0
Última Atualização: Outubro de 2025
Responsável: Equipe de Desenvolvimento CordenaAi